Gesture relations #3693

m-bert · 2025-08-26T13:17:24Z

Important

Supersede #3664.

I've decided to create a separate PR since it was easier to start working on it directly than waiting for #3682 to be merged.

Description

This PR introduces hooks to set relations between handlers.

API

New API replaces the old one as follows:

Gesture.Race(g1, g2) $\rightarrow$ useRace(g1, g2)
Gesture.Exclusive(g1, g2) $\rightarrow$ useExclusive(g1, g2)
Gesture.Simultaneous(g1, g2) $\rightarrow$ useSimultaneous(g1, g2)

Algorithm for populating relations

Handling external relations

In order to properly handle gesture relations, we need to pass 3 arrays to the native side:

waitFor - responsible for handling Exclusive and requireExternalGestureToFail relations
simultaneousHandlers - responsible for Simultaneous and simultaneousWithExternalGesture relations
blocksHandlers - responsible for blocksExternalGesture relation

At first, these arrays are filled with external relations in useGesture hook. Then we use DFS algorithm to add remaining relations, added with relation hooks. Since Race doesn't really change anything when it comes to gesture interactions, we can ignore it in our algorithm.

DFS overview

We use DFS because gesture relations form tree structure.

The algorithm works as follows:

Initialize two arrays: waitFor and simultaneousHandlers. If root node is SimultaneousGesture, we also add its handler tags into simultaneousHandlers array. This ensures that the algorithm works even if we have only Simultaneous as the root node (e.g. useSimultaneous(g1, g1))
Traverse the gesture tree:
- If we are not in the ComposedGesture, it means that we reached leaf node. In that case we populate waitFor and simultanoursHandlers arrays into node arrays and then update relations on the native side
- If we are in the ComposedGesture, then for each child:
  - If the child is not ComposedGesture:
    - We call traverseGestureRelations to reach stop condition and configure relations on the native side
    - If current node is Exclusive, then we add child tag to waitFor array
  - If the child is ComposedGesture:
    - On the way down:
      - Going from non-simultaneous gesture to simultaneous gesture we add all child tags into global simulatneousHandlers array
      - If we go from simultaneous to non-simultaneous gesture, we remove child tags instead of adding.
    - We store length of waitFor to reset it later.
    - We call traverseGestureRelations
    - On the way back:
      - if we go from simultaneous (child) to non-simultaneous (node) gesture, we remove node tags from simultaneousHandlers
      - Going from non-simultaneous (child) to simultaneous (node) gesture we add node tags instead of removing
      - Returning to Exclusive gesture means that we want to add all children tags into waitFor
      - If we return from Exclusive child to non-exclusive node, we want to reset waitFor to previous state, using length variable.

Example

Below you can see example of the algorithm.

We use the following notation:

Handlers and composition:
- E - Exclusive
- S - Simultaneous
- P - Pan
- T - Tap
Relation arrays:
- SH - simultaneousHandlers
- WF - waitFor
Operators:
- += - adding tags
- -= - removing tags

Note: vertex label in relation arrays expands to all tags in the composed gesture.

graph TB
    E1["E₁"] --> |SH += S₁| S1
    E1["E₁"] --> |SH += S₂| S2

    S1["S₁"] --> |SH -= S₁ <br/> WF += S₁| E1
    S1 --> |SH -= E₂| E2
    S1 --> P3
    E2["E₂"] --> |SH += E₂ <br/> WF -= E₂| S1
    P3["P₃ <br/> SH: #91;T₁, T₂, P₃#93;<br/>WF: #91;#93;"] --> S1

    E2 --> T1
    E2 --> T2
    T1["T₁ <br/> SH: #91;P₃#93;<br/>WF: #91;#93;"] --> |WF += T₁| E2
    T2["T₂ <br/> SH: #91;P₃#93;<br/>WF: #91;T₁#93;"] --> |WF += T₂| E2

    S2["S₂"] -->|SH -= S₂| E1
    S2 --> P4
    S2 --> P5
    P4["P₄ <br/> SH: #91;P₄, P₅#93;<br/>WF: #91;T₁, T₂, P₃#93;"] --> S2
    P5["P₅ <br/> SH: #91;P₄, P₅#93;<br/>WF: #91;T₁, T₂, P₃#93;"] --> S2

    style DFS fill-opacity:0,stroke-opacity:0,stroke-width:0px

Limitations

Currently the following setup doesn't work on android:

const composedGesture = useExclusive(tap1, useRace(pan1, pan2));

I've managed to find out what is the difference between this and using only useRace.

Warning

This problem seems to be present also on main, so I think it will be better to solve it in the follow-up PR.

For now, external relation props do not support composed gestures. Let me know if this should be done in this PR, or in a follow-up.

Test plan

Same detector interactions

Verified that the following relations work:

Android

iOS

Base code used for testing:

import * as React from 'react';
import { Animated, Button, useAnimatedValue } from 'react-native';
import {
  GestureHandlerRootView,
  NativeDetector,
  useSimultaneous,
  useGesture,
  useExclusive,
  useRace,
} from 'react-native-gesture-handler';

export default function App() {
  const [visible, setVisible] = React.useState(true);

  const value = useAnimatedValue(0);
  const event = Animated.event(
    [{ nativeEvent: { handlerData: { translationX: value } } }],
    {
      useNativeDriver: true,
    }
  );

  const tap1 = useGesture('TapGestureHandler', {
    onEnd: () => {
      // 'worklet';
      console.log('Tap 1');
    },
    numberOfTaps: 1,
    disableReanimated: true,
  });

  const tap2 = useGesture('TapGestureHandler', {
    onEnd: () => {
      // 'worklet';
      console.log('Tap 2');
    },
    numberOfTaps: 2,
    disableReanimated: true,
  });

  const pan1 = useGesture('PanGestureHandler', {
    // onUpdate: event,
    onUpdate: (e) => {
      // 'worklet';
      console.log('Pan 1');
    },
    disableReanimated: true,
  });

  const pan2 = useGesture('PanGestureHandler', {
    onUpdate: (e) => {
      // 'worklet';
      console.log('Pan 2');
    },
    disableReanimated: true,
  });

  const composedGesture = useSimultaneous(pan1, pan2);

  // const composedGesture = useExclusive(tap2, tap1);
  // const composedGesture = useExclusive(pan2, pan1); // For Animtaed.Event
  // const composedGesture = useExclusive(pan1, pan2); // For Animtaed.Event

  // const composedGesture = useRace(pan1, pan2);
  // const composedGesture = useRace(pan2, pan1);

  // const composedGesture = useExclusive(tap1, useSimultaneous(pan1, pan2));

  return (
    <GestureHandlerRootView
      style={{ flex: 1, backgroundColor: 'white', paddingTop: 8 }}>
      <Button
        title="Toggle visibility"
        onPress={() => {
          setVisible(!visible);
        }}
      />

      {visible && (
        <NativeDetector gesture={composedGesture}>
          <Animated.View
            style={[
              {
                width: 150,
                height: 150,
                backgroundColor: 'blue',
                opacity: 0.5,
                borderWidth: 10,
                borderColor: 'green',
                marginTop: 20,
                marginLeft: 40,
              },
              { transform: [{ translateX: value }] },
            ]}
          />
        </NativeDetector>
      )}
    </GestureHandlerRootView>
  );
}

Cross detector interactions

Verified that the following relations work:

Android

iOS

Base code used for testing:

import * as React from 'react';
import { Animated, Button, useAnimatedValue } from 'react-native';
import {
  GestureHandlerRootView,
  NativeDetector,
  useSimultaneous,
  useGesture,
  useExclusive,
  useRace,
} from 'react-native-gesture-handler';

export default function App() {
  const [visible, setVisible] = React.useState(true);

  const value = useAnimatedValue(0);
  const event = Animated.event(
    [{ nativeEvent: { handlerData: { translationX: value } } }],
    {
      useNativeDriver: true,
    }
  );

  const tap1 = useGesture('TapGestureHandler', {
    onEnd: () => {
      // 'worklet';
      console.log('Tap 1');
    },
    numberOfTaps: 1,
    disableReanimated: true,
  });

  const tap2 = useGesture('TapGestureHandler', {
    onEnd: () => {
      // 'worklet';
      console.log('Tap 2');
    },
    numberOfTaps: 2,
    disableReanimated: true,
    blocksExternalGesture: tap1,
  });

  // const tap1 = useGesture('TapGestureHandler', {
  //   onEnd: () => {
  //     'worklet';
  //     console.log('Tap 1');
  //   },
  //   numberOfTaps: 1,
  //   // disableReanimated: true,
  //   requireExternalGestureToFail: tap2,
  // });

  const pan1 = useGesture('PanGestureHandler', {
    // onUpdate: event,
    onUpdate: (e) => {
      'worklet';
      console.log('Pan 1');
    },
    // disableReanimated: true,
  });

  const pan2 = useGesture('PanGestureHandler', {
    onUpdate: (e) => {
      'worklet';
      console.log('Pan 2');
    },
    simultaneousWithExternalGesture: pan1,
    // requireExternalGestureToFail: pan1,
    // blocksExternalGesture: pan1,
    // disableReanimated: true,
  });

  // const composedGesture = useSimultaneous(pan1, pan2);

  // const composedGesture = useExclusive(tap2, tap1);
  // const composedGesture = useExclusive(pan2, pan1); // For Animated.Event
  // const composedGesture = useExclusive(pan1, pan2); // For Animated.Event

  // const composedGesture = useRace(pan1, pan2);
  // const composedGesture = useRace(pan2, pan1);

  // const composedGesture = useExclusive(tap1, useSimultaneous(pan1, pan2));

  return (
    <GestureHandlerRootView
      style={{ flex: 1, backgroundColor: 'white', paddingTop: 8 }}>
      <Button
        title="Toggle visibility"
        onPress={() => {
          setVisible(!visible);
        }}
      />

      {visible && (
        <NativeDetector gesture={pan1}>
          <Animated.View
            style={[
              {
                width: 150,
                height: 150,
                backgroundColor: 'blue',
                opacity: 0.5,
                borderWidth: 10,
                borderColor: 'green',
                marginTop: 20,
                marginLeft: 40,
                display: 'flex',
                alignItems: 'center',
                justifyContent: 'space-around',
              },
              { transform: [{ translateX: value }] },
            ]}>
            <NativeDetector gesture={pan2}>
              <Animated.View
                style={{ width: 100, height: 100, backgroundColor: 'green' }}
              />
            </NativeDetector>
          </Animated.View>
        </NativeDetector>
      )}
    </GestureHandlerRootView>
  );
}

…ns-v2

m-bert · 2025-09-05T08:46:34Z

packages/react-native-gesture-handler/src/v3/types.ts

+export type ComposedGestureType = ValueOf<typeof ComposedGestureType>;
+
+// TODO: Find better name
+export const HandlerType = {


I'm not sure about this name so if you have any idea how to name it let me know 😅

m-bert added 30 commits August 21, 2025 11:25

Separate Reanimated from JS in NativeDetector

daa017c

Separate Reanimated on Android

1e17cf8

Separate Reanimated on iOS

08d1e2b

Reorganize structure

256f707

Create ceparate hooks for Reanimated

19fd985

Add checks in useGesture

133319b

use isAnimatedEvent

e50f6cc

Extract handlers in separate function

b3ef022

Pass correct touch event callback

952fbe1

Merge branch 'next' into @mbert/extract-reanimated-handlers

ec9eaa7

Merge branch 'next' into @mbert/extract-reanimated-handlers

60a56e6

Fix crash when onUpdate is Animated.Event

fda23cc

Unify lateinit

e46554b

Rename EventTarget on Android

13f3af4

Rename EventTarget on iOS

d7a2b1a

Add reset for animated and reanimated events flags

1b04d3c

Rename getter for event handlers

b8df015

Correctly handle disableReanimated

93343da

Unpack nativeEvent

d1d3efb

Bring back hooks

03a1e64

Use old name

cc1313a

Disable coalescing on Android

dac39cf

Implement DFS for gesture relations

51b5a86

Implement module method for updating relations

92b4a3a

Add blocksHandlers array

e73ee57

Handle Simultaneous as root

432aee0

Change name to enum

b09d746

Move DFS to other file

db5d261

Do not traverse single gestures

43212af

Handle external relations

4ec26c0

m-bert added 4 commits August 26, 2025 12:14

Add exports for type

f62a6df

Add composed handler

504feae

Merge branch 'next' into @mbert/extract-reanimated-handlers

122613f

Merge branch '@mbert/extract-reanimated-handlers' into @mbert/relatio…

246f096

…ns-v2

m-bert mentioned this pull request Aug 26, 2025

Implement gesture relations #3664

Closed

m-bert added 13 commits August 26, 2025 15:47

Rename dfs

e229d84

Split utils

fac31e2

Merge branch 'next' into @mbert/extract-reanimated-handlers

53ce245

Change hook eslint rule to warning

fb88c8c

Extract choosing handler type into function

8e5f07e

Rename event handlers

feaa167

Improve error message

3f2ea8c

Move for loop inside function

4022b96

Merge branch '@mbert/extract-reanimated-handlers' into @mbert/relatio…

8d9fc49

…ns-v2

Do not drop relataions on config change

2dc44b8

Rename method

fab60e5

Merge branch '@mbert/extract-reanimated-handlers' into @mbert/relatio…

31c0e8b

…ns-v2

Rename files to camelCase

832ffb0

Base automatically changed from @mbert/extract-reanimated-handlers to next September 5, 2025 08:09

m-bert and others added 3 commits September 5, 2025 10:21

Merge branch 'next' into @mbert/relations-v2

bea99ab

Rename files to camelCase

fb8c8e3

Remove todo

192556e

m-bert commented Sep 5, 2025

View reviewed changes

Make simultaneousWithExternalGesture symmetric

7c7876b

m-bert marked this pull request as ready for review September 5, 2025 12:49

m-bert requested review from j-piasecki, latekvo and akwasniewski September 5, 2025 12:49

m-bert added 2 commits September 5, 2025 15:04

Fix crash with animated

3e2b661

Add todo

8cd19ff

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Gesture relations #3693

Gesture relations #3693

Uh oh!

m-bert commented Aug 26, 2025 •

edited

Loading

Uh oh!

m-bert Sep 5, 2025

Uh oh!

Uh oh!

Uh oh!

Gesture relations #3693

Are you sure you want to change the base?

Gesture relations #3693

Uh oh!

Conversation

m-bert commented Aug 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

API

Algorithm for populating relations

Handling external relations

DFS overview

Example

Limitations

Test plan

Same detector interactions

Cross detector interactions

Uh oh!

m-bert Sep 5, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

m-bert commented Aug 26, 2025 •

edited

Loading